## A.5. Attributes Common to All Handles

These attributes are common to all types of DBI handles.

Some attributes are inherited by child handles. That is, the value of an inherited attribute in a newly created statement handle is the same as the value in the parent database handle. Changes to attributes in the new statement handle do not affect the parent database handle and changes to the database handle do not affect existing statement handles, only future ones.

Attempting to set or get the value of an unknown attribute is fatal, except for private driver-specific attributes (which all have names starting with a lowercase letter).

For example:

>     $h->{AttributeName} = ...;    # set/write
>     ... = $h->{AttributeName};    # get/read

Warn ( boolean, inherited) |

Enables useful warnings for certain bad practices. Enabled by default. Some emulation layers, especially those for Perl 4 interfaces, disable warnings. Since warnings are generated using the Perl `warn` function, they can be intercepted using the Perl `$SIG{_ _WARN_ _}` hook.

Active ( boolean, read-only) |

True if the handle object is "active." This is rarely used in applications. The exact meaning of active is somewhat vague at the moment. For a database handle, it typically means that the handle is connected to a database (`$dbh-`>`disconnect` sets `Active` off ). For a statement handle, it typically means that the handle is a `SELECT` that may have more data to fetch. (Fetching all the data or calling `$sth-`>`finish` sets `Active` off.)

Kids (integer, read-only) |

For a driver handle, `Kids` is the number of currently existing database handles that were created from that driver handle. For a database handle, `Kids` is the number of currently existing statement handles that were created from that database handle.

ActiveKids (integer, read-only) |

Like `Kids`, but only counting those that are `Active` (as above).

CachedKids (hash ref) |

For a database handle, returns a reference to the cache (hash) of statement handles created by the `prepare_cached` method. For a driver handle, returns a reference to the cache (hash) of database handles created by the `connect_cached` method.

CompatMode ( boolean, inherited) |

Used by emulation layers (such as Oraperl) to enable compatible behavior in the underlying driver (e.g., `DBD::Oracle`) for this handle. Not normally set by application code.

InactiveDestroy ( boolean) |

This attribute can be used to disable the database engine related effect of destroying a handle (which would normally close a prepared statement or disconnect from the database, etc.).

For a database handle, this attribute does not disable an explicit call to the disconnect method, only the implicit call from DESTROY.

This attribute is specifically designed for use in Unix applications that "fork" child processes. Either the parent or the child process, but not both, should set `InactiveDestroy` on all their shared handles.

PrintError ( boolean, inherited) |

This attribute can be used to force errors to generate warnings (using `warn`) in addition to returning error codes in the normal way. When set "on," any method that results in an error occurring will cause the DBI to effectively do a `warn("$class` `$method` `failed:` `$DBI::errstr")` where `$class` is the driver class, and `$method` is the name of the method which failed.

For example:

>     DBD::Oracle::db prepare failed: ... error text here ...

By default, `DBI-`>`connect` sets `PrintError` to "on."

If desired, the warnings can be caught and processed using a `$SIG{_ _WARN_ _}` handler or modules like `CGI::Carp` and `CGI::ErrorWrap`.

RaiseError ( boolean, inherited) |

This attribute can be used to force errors to raise exceptions rather than simply return error codes in the normal way. It is "off " by default. When set to "on", any method that results in an error will cause the DBI to effectively do a `die("$class $method failed: $DBI::errstr")`, where `$class` is the driver class, and `$method` is the name of the method that failed. For example:

>     DBD::Oracle::db prepare failed: ... error text here ...

If `PrintError` is also on, then the `PrintError` is done before the `RaiseError` unless no `_ _DIE_ _` handler has been defined, in which case `PrintError` is skipped, since the `die` will print the message.

If you want to temporarily turn `RaiseError` off (inside a library function that is likely to fail, for example), the recommended way is like this:

>     {
>       local $h->{RaiseError}; # localize and turn off for this block
>       ...
>     }

The original value will automatically and reliably be restored by Perl, regardless of how the block is exited. The same logic applies to other attributes, including `PrintError`.

Sadly, this doesn't work for Perl versions up to and including 5.004_04. For backwards compatibility, you could just use `eval` `{` `...` `}` instead.

ChopBlanks ( boolean, inherited) |

This attribute can be used to control the trimming of trailing space characters from fixed-width character (CHAR) fields. No other field types are affected, even where field values have trailing spaces.

The default is false (although it is possible that the default may change). Applications that need specific behavior should set the attribute as needed. Emulation interfaces should set the attribute to match the behavior of the interface they are emulating.

Drivers are not required to support this attribute, but any driver that does not support it must arrange to return `undef` as the attribute value.

LongReadLen (unsigned integer, inherited) |

This attribute may be used to control the maximum length of long fields ("blob," "memo," etc.), which the driver will read from the database automatically when it fetches each row of data. The `LongReadLen` attribute relates only to fetching and reading long values; it is not involved in inserting or updating them.

A value of `0` means not to automatically fetch any long data. (`fetch` should return `undef` for long fields when `LongReadLen` is `0`.)

The default is typically `0` (zero) bytes but may vary between drivers. Applications fetching long fields should set this value to slightly larger than the longest long field value to be fetched.

Some databases return some long types encoded as pairs of hex digits. For these types, `LongReadLen` relates to the underlying data length and not the doubled-up length of the encoded string.

Changing the value of `LongReadLen` for a statement handle after it has been `prepare`'d will typically have no effect, so it's common to set `LongReadLen` on the `$dbh` before calling `prepare`.

Note that the value used here has a direct effect on the memory used by the application, so don't be too generous.

See `LongTruncOk` for more information on truncation behavior.

LongTruncOk ( boolean, inherited) |

This attribute may be used to control the effect of fetching a long field value that has been truncated (typically because it's longer than the value of the `LongReadLen` attribute).

By default, `LongTruncOk` is false, and so fetching a long value that needs to be truncated will cause the fetch to fail. (Applications should always be sure to check for errors after a fetch loop in case an error, such as a divide by zero or long field truncation, caused the fetch to terminate prematurely.)

If a fetch fails due to a long field truncation when `LongTruncOk` is false, many drivers will allow you to continue fetching further rows.

See also `LongReadLen`.

Taint ( boolean, inherited) |

If this attribute is set to a true value and Perl is running in taint mode (e.g., started with the `-T` option), then all data fetched from the database is tainted, and the arguments to most DBI method calls are checked for being tainted. This may change.

The attribute defaults to off, even if Perl is in taint mode. See the perlsec manpage for more about taint mode. If Perl is not running in taint mode, this attribute has no effect.

When fetching data that you can trust, you can turn off the taint attribute for that statement handle, for the duration of the fetch loop.

Currently only fetched data is tainted. It is possible that the results of other DBI method calls, and the value of fetched attributes, may also be tainted in future versions. That change may well break your applications unless you take great care now. If you use DBI taint mode, please report your experience and any suggestions for changes.

private_* |

The DBI provides a way to store extra information in a DBI handle as "private" attributes. The DBI will allow you to store and retrieve any attribute that has a name starting with `private_`. It is strongly recommended that you use just one private attribute (e.g., use a hash ref) and give it a long and unambiguous name that includes the module or application name that the attribute relates to (e.g., `private_YourFullModuleName_thingy`).

Copyright © 2001 O'Reilly & Associates. All rights reserved.